Knightdreams'Blog

Appearance

Codex Prompt 实战指南：如何把需求正确地交给 Coding Agent ​

前面几篇我们已经介绍了：

text
Codex CLI
AGENTS.md
Slash Commands
Plan
Permissions
Review

但真正开始使用 Codex 以后，会发现一个非常关键的问题：

text
同一个 Codex
同一个模型
同一个项目

为什么不同的人使用，
效果差距会这么大？

其中一个非常重要的原因就是：

text
Prompt

例如有人会直接告诉 Codex：

text
帮我优化一下这个项目。

这句话看起来没什么问题。

但对于 Coding Agent 来说：

text
优化什么？
允许修改哪里？
哪些地方不能动？
能不能改数据库？
能不能升级依赖？
要不要跑测试？
能不能提交 Git？
什么结果才算完成？

全部没有说明。

Agent 只能自己判断。

而 Agent 自己判断得越多：

text
结果的不确定性
就越高

所以使用 Coding Agent 时，一个非常重要的能力不是：

text
会不会写很长的 Prompt

而是：

text
能不能把任务边界描述清楚

这一篇就专门讲：

如何把一个真实的软件开发需求，正确地交给 Codex。

1. Coding Agent Prompt 和普通 Chat Prompt 不一样 ​

普通 ChatGPT Prompt 很多时候只是：

text
Question
   ↓
Answer

例如：

text
Java 的 synchronized 和 ReentrantLock 有什么区别？

AI 回答以后，任务基本结束。

但 Codex 不一样。

Codex 更接近：

text
Task
   ↓
Understand
   ↓
Search
   ↓
Plan
   ↓
Modify
   ↓
Execute
   ↓
Test
   ↓
Review

所以你给 Codex 的 Prompt，本质上不是：

text
问题

而更像：

text
任务单

可以理解成：

text
普通 Chat Prompt
≈ 问一个同事问题

Codex Prompt
≈ 给一个开发者分配任务

这也是为什么 Coding Agent 的 Prompt 更需要：

text
目标
范围
约束
验收标准

2. 最差的一类 Prompt：帮我优化一下 ​

例如：

text
帮我优化 UserService。

这句话最大的问题不是短。

而是：

text
没有边界

所谓：

text
优化

可能包括：

text
修改变量名
拆方法
改类结构
升级依赖
修改 SQL
增加缓存
修改数据库
增加线程池
修改接口
删除旧代码

Agent 很难知道你真正想要什么。

甚至：

text
你认为是“重构”
Agent 认为是“架构升级”

最后 Diff 可能越来越大。

3. 更好的 Prompt 应该怎么写？ ​

例如原始需求：

text
优化 UserRewardService。

可以改成：

text
优化 UserRewardService 的可读性。

范围：

只允许修改：

- UserRewardService.java
- UserRewardServiceImpl.java

要求：

1. 不改变现有业务逻辑
2. 不修改 public API
3. 不修改数据库结构
4. 不新增第三方依赖
5. 可以提取重复的 private 方法
6. 可以改善变量和方法命名

验证：

1. 编译相关模块
2. 运行现有相关测试
3. 检查 git diff

完成后告诉我：

1. 修改了什么
2. 为什么这样修改
3. 测试结果
4. 是否存在潜在风险

这样 Codex 得到的信息就完整很多。

4. 一个好 Prompt 的六个核心部分 ​

可以记一个简单公式：

text
Codex Prompt

=

Context
+
Goal
+
Scope
+
Constraints
+
Verification
+
Output

中文就是：

text
上下文
+
目标
+
范围
+
约束
+
验证
+
输出要求

这六个部分不一定每次全部写。

但是对于复杂任务，非常值得明确。

5. Context：告诉 Codex 当前背景 ​

Context 就是：

text
上下文

例如：

text
这是一个 Java 17 + Spring Boot 项目。

当前用户充值流程：

链上扫描
→ DepositRecord
→ 确认区块数
→ 用户余额入账

或者：

text
用户反馈关闭 SSE 页面以后，
后端偶尔出现 Broken pipe 异常日志。

接口使用 Spring MVC SseEmitter。

Context 的目的不是把整个项目复制给 Codex。

因为 Codex 自己可以读代码。

真正有价值的是：

text
代码里不容易知道的信息

例如：

text
为什么要改
线上出现了什么问题
业务期望是什么
哪些行为必须兼容

6. Context 不要写成项目百科全书 ​

例如没必要这样：

text
我们公司成立于……
这个项目从 2022 年开始……
一共有 36 个模块……

除非这些信息和任务直接相关。

更好的 Context 应该满足：

text
和当前任务有关
+
代码中不容易直接推断
+
能够帮助 Agent 做决策

例如：

text
当前 App 旧版本仍然依赖这个 API，
所以返回字段不能删除或改名。

这就是非常高价值的 Context。

7. Goal：明确到底要完成什么 ​

Goal 是整个 Prompt 最核心的部分。

例如：

text
修复用户余额重复扣减问题。

或者：

text
给充值确认流程增加幂等保护。

或者：

text
把重复的链上 RPC 请求逻辑抽象成统一 RpcClient。

一个好的 Goal 应该尽量：

text
具体
可判断是否完成

不推荐：

text
优化一下
完善一下
看看有没有问题
改得更好一点

这些词都太模糊。

8. Scope：限制 Codex 可以动哪里 ​

这是 Coding Agent Prompt 中特别重要的一部分。

例如：

text
范围：

只分析 payment 和 order 模块。

或者：

text
只允许修改：

UserRewardService.java
UserRewardServiceImpl.java

或者：

text
允许修改：

wallet 模块
相关单元测试
必要的 migration SQL

为什么 Scope 很重要？

因为 Codex 有能力搜索整个 Repository。

如果没有范围：

text
一个小需求

可能最后变成：

text
跨十几个模块修改

Agent 能力越强：

text
Scope 越重要

9. Scope 不一定只写文件 ​

Scope 可以有很多形式。

按模块 ​

text
只处理：

payment
order

按目录 ​

text
只允许修改：

src/main/java/com/example/wallet
src/test/java/com/example/wallet

按文件 ​

text
只修改：

UserService.java
UserServiceImpl.java

按行为 ​

text
只修复 Bug，
不要进行额外重构。

实际使用时可以组合。

10. Constraints：明确哪些事情不能做 ​

Constraints 就是：

text
约束

例如：

text
要求：

1. 不修改现有 API
2. 不修改数据库结构
3. 不新增依赖
4. 保持向后兼容
5. 不修改生产配置
6. 不提交 Git

这部分非常重要。

因为开发任务通常不是：

text
只要实现功能就行

而是：

text
在很多限制条件下实现功能

真正的软件工程就是这样。

11. 把“禁止事项”单独写出来 ​

对于风险比较高的任务，可以直接增加：

text
禁止：

例如：

text
禁止：

1. git push
2. git reset --hard
3. 修改生产环境配置
4. 删除数据库字段
5. 修改历史 migration
6. 调用生产接口

虽然这些长期规则更适合写进：

text
AGENTS.md

但如果当前任务特别敏感，也可以在 Prompt 中再次强调。

12. Verification：怎么证明任务完成了？ ​

这是很多 Prompt 最容易遗漏的一部分。

例如你告诉 Codex：

text
修复这个 Bug。

它修改完代码以后：

text
任务完成了吗？

不一定。

因为：

text
能编译吗？
测试通过吗？
有没有破坏旧逻辑？
Diff 是否符合预期？

都还不知道。

所以应该明确：

text
验证：

1. 编译相关模块
2. 运行相关单元测试
3. 检查 git diff

如果是 Maven：

text
验证：

1. 执行 mvn test
2. 如果全量测试过慢，至少运行目标模块测试
3. 检查是否存在编译错误
4. 检查 git diff

这会让 Codex 从：

text
写完代码

继续走到：

text
验证代码

13. Verification 是 Coding Agent 的核心优势之一 ​

普通 AI 生成代码以后：

text
你复制
↓
你编译
↓
你发现错误
↓
你再复制错误回来

而 Codex 可以：

text
修改
↓
编译
↓
失败
↓
读取错误
↓
继续修复
↓
再次测试

所以不要只让 Codex：

text
Generate

应该尽量让它：

text
Generate
+
Verify

这才真正发挥 Agent 的价值。

14. Output：最后让 Codex 怎么汇报？ ​

完成任务以后，最好让 Codex给一个结构化总结。

例如：

text
完成后输出：

1. 问题根因
2. 实现方案
3. 修改文件
4. 测试结果
5. 潜在风险

为什么有用？

因为 Coding Agent 可能修改多个文件。

如果最后只是：

text
Done.

开发者还要自己重新梳理。

而结构化输出可以帮助快速 Review。

15. 一个完整的通用 Prompt 模板 ​

可以长期保存下面这个模板：

text
任务：

<要完成什么>

背景：

<当前问题和必要上下文>

范围：

<允许分析或修改哪些模块 / 文件>

要求：

1. <要求1>
2. <要求2>
3. <要求3>

禁止：

1. <禁止事项1>
2. <禁止事项2>

验证：

1. 编译相关模块
2. 运行相关测试
3. 检查 git diff

完成后输出：

1. 问题原因
2. 实现方案
3. 修改文件
4. 测试结果
5. 潜在风险

复杂任务再增加：

text
先分析并制定计划。

不要立即修改代码。

等方案确认以后再实施。

16. 模板一：Bug 修复 ​

例如：

text
任务：

修复用户关闭 SSE 页面以后，
后端出现 Broken pipe 异常日志的问题。

背景：

接口使用 Spring MVC SSE。
用户主动关闭页面以后，
服务端继续向连接写数据时可能抛出异常。

范围：

只分析：

- SSE Controller
- SSE Service
- GlobalExceptionHandler

要求：

1. 先找到异常真正产生的位置
2. 判断这是正常客户端断连还是服务端 Bug
3. 不改变现有 SSE API
4. 不吞掉其他真正的 IOException
5. 只处理与客户端断连相关的异常

验证：

1. 编译相关模块
2. 运行相关测试
3. 检查 git diff

完成后输出：

1. 根因
2. 修改方案
3. 修改文件
4. 为什么不会影响其他异常
5. 测试结果

这个 Prompt 比：

text
帮我修 Broken pipe

稳定得多。

17. 模板二：查调用链 ​

Codex 很适合做：

text
Repository Search

例如：

text
任务：

分析 UserBalanceService.opsBalance 的完整调用情况。

先不要修改代码。

请：

1. 找出所有直接调用方
2. 找出间接调用链
3. 按业务场景分类
4. 标记每个调用是增加余额还是减少余额
5. 找出调用涉及的事务
6. 找出是否存在异步调用
7. 找出是否存在重复入账风险

最后按照下面格式输出：

业务场景
→ 调用入口
→ 调用链
→ amount 变化
→ 事务
→ 幂等机制
→ 风险

不要修改任何文件。

这比单纯：

text
找一下谁调用了 opsBalance

获得的信息更有价值。

18. 模板三：重构 ​

重构任务尤其需要限制范围。

例如：

text
任务：

重构重复的链上 RPC 调用逻辑。

目标：

把 BSC 和 TRON 公共能力抽象到 RpcClient 接口。

范围：

只允许修改：

- RpcClient
- BSCRpcClient
- TronRpcClient
- RpcClientHolder
- 相关测试

要求：

1. 不改变现有业务行为
2. 不修改数据库结构
3. 不修改外部 API
4. 不新增第三方依赖
5. 保持现有异常处理行为
6. 公共逻辑尽量抽象，链特有逻辑保留在实现类

先不要修改代码。

先输出：

1. 当前重复逻辑
2. 建议接口设计
3. 需要修改的文件
4. 兼容性风险
5. 测试方案

等待确认以后再实施。

注意这里加入了：

text
先不要修改

因为重构通常值得先 Plan。

19. 模板四：新增功能 ​

例如：

text
任务：

增加用户余额冻结功能。

要求支持：

freeze
unfreeze

范围：

wallet 模块。

要求：

1. available balance 不允许小于 0
2. freeze 必须幂等
3. unfreeze 必须幂等
4. 所有余额变化必须记录流水
5. 金额使用 BigDecimal
6. 保持现有余额查询 API 兼容

先分析：

1. 当前余额表结构
2. 当前余额修改入口
3. 提现流程
4. 充值流程
5. 事务边界
6. 并发控制

然后给出实现方案。

当前阶段不要修改代码。

这种需求如果直接：

text
帮我增加冻结余额

很容易遗漏：

text
事务
幂等
流水
并发
兼容

20. 模板五：Code Review ​

例如：

text
Review 当前 Git Diff。

不要修改代码。

重点检查：

1. 空指针
2. 边界条件
3. 并发问题
4. MySQL 事务
5. Redis 一致性
6. MQ 重复消费
7. BigDecimal 精度
8. SQL 性能
9. 向后兼容
10. 安全问题

对于每个问题输出：

- 严重程度
- 文件
- 代码位置
- 问题原因
- 可能后果
- 建议修改方式

如果没有发现明确问题，不要为了输出内容而猜测问题。

最后一句很重要：

text
不要为了输出内容而猜测问题

可以减少：

text
为了 Review 而 Review

的情况。

21. 模板六：单元测试 ​

例如：

text
任务：

给 RewardService 增加单元测试。

先阅读现有测试代码，
保持项目当前测试风格。

覆盖：

1. level = 1
2. level = 8
3. amount = null
4. amount = 0
5. 正常多级奖励
6. 边界金额
7. 重复业务请求

要求：

1. 不修改生产代码，除非确实无法测试
2. 优先复用现有测试工具
3. 不新增测试框架
4. 测试名称能够表达业务场景

完成后：

1. 运行新增测试
2. 输出测试结果
3. 说明覆盖了哪些边界条件

这比：

text
帮我写几个测试

清晰很多。

22. 模板七：数据库修改 ​

数据库修改建议更加保守。

例如：

text
任务：

给 stake_order 增加 settlement_time 字段。

先不要修改。

请先分析：

1. 当前 Entity
2. Mapper
3. SQL
4. migration 方式
5. settlement_flag 的使用位置

要求：

1. 保持旧数据兼容
2. 不修改历史 migration
3. 提供新的 migration SQL
4. 不删除或重命名已有字段
5. 分析是否需要索引
6. 分析 null 对旧数据的影响

先给出方案，
确认以后再修改。

对于：

text
Schema Change

非常建议：

text
Plan First

23. 模板八：性能问题 ​

例如：

text
任务：

分析用户邀请树查询速度慢的问题。

当前现象：

用户下级数量较大时，
接口响应时间明显增加。

先不要修改代码。

请分析：

1. Controller 调用链
2. Service 逻辑
3. Neo4j Cypher
4. 是否存在 N+1 查询
5. 是否存在重复查询
6. 是否存在不必要的全量加载
7. 当前索引是否能够支持查询
8. Java 层是否存在低效循环

输出：

1. 性能瓶颈
2. 证据
3. 优化优先级
4. 推荐方案
5. 预计影响范围

不要在没有证据的情况下直接进行大规模重构。

性能优化特别容易出现：

text
凭感觉优化

所以最好要求：

text
先找证据

24. 模板九：解释陌生项目 ​

第一次进入项目时可以：

text
阅读当前 Repository。

先不要修改任何文件。

请分析：

1. 项目技术栈
2. Maven / Gradle 模块
3. 应用启动入口
4. Controller 结构
5. Service 结构
6. 数据库访问方式
7. Redis 使用方式
8. MQ 使用方式
9. 定时任务
10. 外部服务调用
11. 测试结构

最后输出：

项目
├── 模块
├── 核心业务
├── 数据存储
├── 消息系统
├── 外部依赖
└── 测试

如果某个部分无法从代码确认，
明确标记为“未确认”，不要猜测。

这是非常推荐的新项目开场 Prompt。

25. 模板十：让 Codex 自己修到测试通过 ​

对于边界清晰的任务，可以提高 Agent 自主性：

text
修复当前失败的单元测试。

范围：

只处理 wallet 模块。

要求：

1. 先运行目标测试确认失败
2. 找到根因
3. 修复根因，不要仅仅修改测试绕过问题
4. 不修改 public API
5. 不修改数据库结构
6. 不新增依赖

修改以后重新运行测试。

如果仍然失败：

继续分析并修复。

直到：

相关测试通过，
或者发现无法安全继续的阻塞问题。

最后输出：

1. 根因
2. 修改文件
3. 修复方式
4. 最终测试结果

这里就体现了 Coding Agent 和普通聊天 AI 的差别：

text
Run
→ Observe
→ Fix
→ Run Again

26. 什么时候应该让 Codex“先不要修改”？ ​

不是所有任务都需要。

简单任务：

text
修复拼写
修改变量名
增加 null 判断
增加简单测试

可以直接执行。

但下面这些任务推荐：

text
先分析

例如：

text
架构调整
数据库修改
支付
钱包
认证
权限
跨模块重构
并发 Bug
性能优化
复杂线上问题

可以简单判断：

text
如果改错以后回滚成本高
→ 先 Plan

27. 不要把 Prompt 写成“微操 Agent” ​

Prompt 清晰不代表：

text
每一步都必须由人指定

例如没必要写：

text
第一步打开 UserService.java
第二步搜索 getUser
第三步打开 UserMapper
第四步……

这反而限制 Agent。

更好的方式是：

text
告诉它：

目标
范围
约束
验证

至于：

text
具体搜索哪些文件
先执行 grep 还是 rg
先读 Mapper 还是 Service

可以让 Agent 自己决定。

也就是：

text
控制结果和边界
而不是控制每一个动作

28. Prompt 越长越好吗？ ​

不是。

真正好的 Prompt 是：

text
信息密度高

而不是：

text
字数多

例如：

text
修复支付回调重复入账。

约束：

- 保持 API 不变
- 不修改数据库结构
- 使用现有 paymentNo 做幂等
- 不新增 Redis 锁
- 修改范围只限 payment 模块

验证：

- 补重复回调测试
- 运行 payment 模块测试
- 检查 git diff

虽然很短，但已经非常清晰。

29. 哪些东西应该放 AGENTS.md，而不是 Prompt？ ​

如果一条规则：

text
每个任务都要重复

就应该考虑放进：

text
AGENTS.md

例如：

text
Java 17
金额使用 BigDecimal
禁止 git push
Controller 不返回 Entity
修改数据库必须提供 migration

而 Prompt 更适合：

text
当前需求

例如：

text
增加冻结余额
修复重复支付
重构 RpcClient

可以简单理解：

text
AGENTS.md
→ 长期规则

Prompt
→ 当前任务

30. 一个推荐的 Prompt 编写顺序 ​

以后给 Codex 任务时，可以先在脑子里过一遍：

text
① 我要它做什么？
        ↓
② 为什么要做？
        ↓
③ 允许改哪里？
        ↓
④ 哪些东西不能动？
        ↓
⑤ 怎么证明完成了？
        ↓
⑥ 最后我要它告诉我什么？

对应：

text
Goal
Context
Scope
Constraints
Verification
Output

这六个问题回答清楚以后，大多数 Prompt 都不会太差。

31. 最后怎么记？ ​

如果只记一个公式：

text
Codex Prompt

=

Context
+
Goal
+
Scope
+
Constraints
+
Verification
+
Output

也就是：

text
背景
+
目标
+
范围
+
约束
+
验证
+
输出

如果任务复杂，再增加：

text
Plan First

于是完整工作方式就是：

text
AGENTS.md
    ↓
提供长期项目规则

Prompt
    ↓
描述当前任务

Plan
    ↓
复杂任务先设计方案

Implement
    ↓
Codex 修改代码

Verification
    ↓
编译 + 测试

Review
    ↓
Codex Review + Developer Review

真正高质量地使用 Coding Agent，并不是学会一句：

text
“帮我写代码”

而是学会：

text
如何把一个软件工程任务，
完整、准确、有边界地交给 Agent。

当 Prompt 从：

text
帮我优化一下

逐渐变成：

text
明确目标
明确范围
明确约束
明确验证

Codex 的表现通常也会变得：

text
更稳定
更可控
更接近真实的软件工程协作

而这也是从：

text
会使用 AI

走向：

text
会管理 Coding Agent

非常关键的一步。